<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>ExceptionPolicy&lt;EP&gt;</title>
<link rel="stylesheet" href="boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="Safe Numerics">
<link rel="up" href="concepts.html" title="Type Requirements">
<link rel="prev" href="promotion_policy.html" title="PromotionPolicy&lt;PP&gt;">
<link rel="next" href="types.html" title="Types">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img href="index.html" height="164px" src="pre-boost.jpg" alt="Library Documentation Index"></td>
<td><h2>Safe Numerics</h2></td>
</tr></table>
<div class="spirit-nav">
<a accesskey="p" href="promotion_policy.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="concepts.html"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a><a accesskey="n" href="types.html"><img src="images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="safe_numerics.exception_policy"></a>ExceptionPolicy&lt;EP&gt;</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="exception_policy.html#idm462684977056">Description</a></span></dt>
<dt><span class="section"><a href="exception_policy.html#idm462684975648">Notation</a></span></dt>
<dt><span class="section"><a href="exception_policy.html#idm462684966288">Valid Expressions</a></span></dt>
<dt><span class="section"><a href="exception_policy.html#idm462684950432">dispatch&lt;EP&gt;(const safe_numerics_error &amp; e, const char *
    msg)</a></span></dt>
<dt><span class="section"><a href="exception_policy.html#idm462684921760">Models</a></span></dt>
<dt><span class="section"><a href="exception_policy.html#idm462684892144">Header</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm462684977056"></a>Description</h4></div></div></div>
<p>The exception policy specifies what is to occur when a safe
    operation cannot return a valid result. A type is an ExceptionPolicy if it
    has functions for handling exceptional events that occur in the course of
    safe numeric operations.</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm462684975648"></a>Notation</h4></div></div></div>
<div class="informaltable"><table class="table">
<colgroup>
<col align="left">
<col align="left">
</colgroup>
<tbody>
<tr>
<td align="left"><code class="computeroutput">EP</code></td>
<td align="left">A type that fulfills the requirements of an
            ExceptionPolicy</td>
</tr>
<tr>
<td align="left">e</td>
<td align="left">A code from <a class="link" href="exception.html#safe_numerics.safe_numerics_error" title="enum class safe_numerics_error"><code class="computeroutput">safe_numerics_error</code></a>
</td>
</tr>
<tr>
<td align="left">message</td>
<td align="left">A const char * which refers to a text message about the
            cause of an exception</td>
</tr>
</tbody>
</table></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm462684966288"></a>Valid Expressions</h4></div></div></div>
<p>Whenever an operation yield an invalid result, one of the following
    functions will be invoked.</p>
<div class="informaltable"><table class="table">
<colgroup>
<col align="left">
<col align="left">
<col align="left">
</colgroup>
<thead><tr>
<th align="left">Expression</th>
<th align="left">Return Value</th>
<th align="left">Invoked when:</th>
</tr></thead>
<tbody>
<tr>
<td align="left"><code class="computeroutput">EP::on_arithmetic_error(e, message)</code></td>
<td align="left">void</td>
<td align="left">The operation cannot produce valid arithmetic result such
              as overflows, divide by zero, etc.</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">EP::on_undefined_behavior(e,
              message)</code></td>
<td align="left">void</td>
<td align="left">The result is undefined by the C++ standard</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">EP::on_implementation_defined_behavior(e,
              message)</code></td>
<td align="left">void</td>
<td align="left">The result depends upon implementation defined behavior
              according to the C++ standard</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">EP::on_uninitialized_value(e,
              message)</code></td>
<td align="left">void</td>
<td align="left">A variable is not initialized</td>
</tr>
</tbody>
</table></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm462684950432"></a>dispatch&lt;EP&gt;(const safe_numerics_error &amp; e, const char *
    msg)</h4></div></div></div>
<p>This function is used to invoke the exception handling policy for a
    particular exception code.</p>
<div class="section">
<div class="titlepage"><div><div><h5 class="title">
<a name="idm462684949200"></a>Synopsis</h5></div></div></div>
<pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">EP</span><span class="special">&gt;</span>
<span class="keyword">constexpr</span> <span class="keyword">void</span>
<span class="identifier">dispatch</span><span class="special">&lt;</span><span class="identifier">EP</span><span class="special">&gt;</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">numeric</span><span class="special">::</span><span class="identifier">safe_numerics_error</span> <span class="special">&amp;</span> <span class="identifier">e</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span> <span class="special">*</span> <span class="keyword">const</span> <span class="special">&amp;</span> <span class="identifier">msg</span><span class="special">)</span><span class="special">;</span></pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h5 class="title">
<a name="idm462684931440"></a>Example of use</h5></div></div></div>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">safe_numerics</span><span class="special">/</span><span class="identifier">exception_policies</span><span class="special">.</span><span class="identifier">hpp</span><span class="string">"

dispatch&lt;boost::numeric::loose_exception_policy&gt;(
    boost::numeric::safe_numerics_error::positive_overflow_error, 
    "</span><span class="identifier">operation</span> <span class="identifier">resulted</span> <span class="identifier">in</span> <span class="identifier">overflow</span><span class="string">"
);</span></pre>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm462684921760"></a>Models</h4></div></div></div>
<p>The library header <a href="../../include/boost/safe_numerics/exception_policies.hpp" target="_top"><code class="computeroutput">&lt;boost/safe_numerics/exception_policies.hpp&gt;
    </code></a>contains a number of pre-made exception policies:</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p><code class="computeroutput">boost::numeric::loose_exception_policy</code></p>
<p>Throw on arithmetic errors, ignore other errors. Some
        applications ignore these issues and still work and we don't want to
        update them.</p>
</li>
<li class="listitem">
<p><code class="computeroutput">boost::numeric::loose_trap_policy</code></p>
<p>Same as above in that it doesn't check for various undefined
        behaviors but traps at compile time for hard arithmetic errors. This
        policy would be suitable for older embedded systems which depend on
        bit manipulation operations to work.</p>
</li>
<li class="listitem">
<p><code class="computeroutput">boost::numeric::strict_exception_policy</code></p>
<p>Permit just about anything, throw at runtime on any kind of
        error. Recommended for new code. Check everything at compile time if
        possible and runtime if necessary. Trap or Throw as appropriate.
        Should guarantee code to be portable across architectures.</p>
</li>
<li class="listitem">
<p><code class="computeroutput">boost::numeric::strict_trap_policy</code></p>
<p>Same as above but requires code to be written in such a way as
        to make it impossible for errors to occur. This naturally will require
        extra coding effort but might be justified for embedded and/or safety
        critical systems.</p>
</li>
<li class="listitem">
<p><code class="computeroutput">boost::numeric::default_exception_policy</code></p>
<p>Alias for <code class="computeroutput">strict_exception_policy</code>, One would use
        this first. After experimentation, one might switch to one of the
        above policies or perhaps use a custom policy.</p>
</li>
</ul></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm462684892144"></a>Header</h4></div></div></div>
<p><a href="../../include/boost/safe_numerics/concept/exception_policy.hpp" target="_top"><code class="computeroutput">#include
    &lt;boost/safe_numerics/concepts/exception_policy.hpp&gt;
    </code></a></p>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2012-2018 Robert Ramey<p><a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">Subject to Boost
      Software License</a></p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="promotion_policy.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="concepts.html"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a><a accesskey="n" href="types.html"><img src="images/next.png" alt="Next"></a>
</div>
</body>
</html>
